home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / program / tvichw32.zip / README.TXT < prev    next >
Text File  |  1997-03-25  |  12KB  |  300 lines
  1.                            TVicHw32 version 1.1
  2.  
  3.                    Copyright (C) 1997 Victor Ishikeev
  4.               Portions Copyright (C) 1997 EnTech Taiwan
  5.                      e-mail: tools@entechtaiwan.com
  6.  
  7.                                  README
  8.  
  9.  
  10.  
  11. CONTENTS
  12. ========
  13.  
  14. 1. OVERVIEW
  15. 2. REGISTRATION
  16. 3. INSTALLATION
  17. 4. GENERAL TVicHW32 COMPONENT PROPERTIES AND METHODS
  18. 5. DIRECT MEMORY ACCESS WITH TVicHW32
  19. 6. DIRECT PORT I/O WITH TVicHW32
  20. 7. HARDWARE INTERRUPT HANDLING WITH TVicHW32
  21. 8. CONTACT INFORMATION
  22.  
  23.  
  24. 1. OVERVIEW
  25. ===========
  26.  
  27. TVicHW32 is a shareware component for use with Delphi 2.0 which 
  28. allows you to control hardware from a Win32 application without using
  29. the Windows DDK. TVicHW32 provides transparent support for Windows 95
  30. and Windows NT, providing Delphi programmers with a standard method 
  31. for real-time direct access to port I/O, memory I/O, and hardware 
  32. interrupts - without requiring you to write a custom virtual device
  33. driver for Windows 95 or a kernel-mode driver for NT.
  34.  
  35. Evaluation copies of the TVicHW32 component consist of the following
  36. elements:
  37.  
  38.   - vichw00.vxd and vichw00.sys
  39.     evaluation run-time kernel mode drivers, which manage all port
  40.     and memory I/0, and interrupt handling
  41.   - hw_32.dcu and loadhw.dcu
  42.     Delphi interface units to the kernel mode drivers
  43.   - hw_test.dpr and main.*
  44.     Sample program, with source, demonstrating some of the features
  45.     of the TVicHW32 component
  46.  
  47. 2. REGISTRATION
  48. ===============
  49.  
  50. TVicHW32 is shareware. You must read and accept the terms detailed in
  51. the license.txt file before you can use this component. An order form
  52. is provided in the file order.txt for the purpose of registering this 
  53. component.
  54.  
  55. Registered users will receive:
  56.  
  57.   - vichw11.vxd and vichw11.sys
  58.     royalty-free run-time kernel mode drivers, which manage all port
  59.     and memory I/0, and interrupt handling
  60.   - hw_32.pas and loadhw.pas
  61.     Delphi interface source code to the kernel mode drivers
  62.  
  63. TVicHW32 is maintained at the following internet address:
  64.   http://www.entechtaiwan.com/tools.htm
  65.   e-mail: tools@entechtaiwan.com
  66.  
  67. where you can find the latest release and links to support and on-line
  68. ordering sites.
  69.  
  70. 3. INSTALLATION
  71. ===============
  72.  
  73. TVicHW32 is installed on the "Drivers" page of the VCL palette, by 
  74. following the steps below:
  75.  
  76.   1) Create a directory for the TVicHW32 component, e.g., C:\HW
  77.   2) For use with Windows 95, copy the vichwXX.vxd file to your 
  78.      Windows 95 system directory, e.g., C:\WINDOWS\SYSTEM
  79.   3) For use with Windows NT, copy the vichwXX.sys file to your
  80.      Windows NT drivers directory, e.g., C:\WINDOWS\SYSTEM32\DRIVERS
  81.   4) Add the TVicHW32 component to your Delphi component library by
  82.      selecting Component|Install|Add... and then click Ok to rebuild
  83.      the library
  84.  
  85. 4. GENERAL TVicHW32 COMPONENT PROPERTIES AND METHODS
  86. ====================================================
  87.  
  88. After successfully adding the TVicHW32 component to your VCL, and
  89. after copying the kernel-mode driver(s) to the appropriate Windows
  90. directories, you can test the functionality of the component, and 
  91. examine the sample code provided, by opening the included HW_TEST 
  92. demonstration program.
  93.  
  94. TVicHW32 has the following general component properties and methods:
  95.  
  96.     constructor Create (Owner: TComponent); override;
  97.     -------------------------------------------------
  98.     The Create method allocates memory to create the TVicHW32 
  99.     component and initializes data as needed. Note that Create does 
  100.     *not* automatically open the kernel-mode driver: you must open the
  101.     kernel-mode driver with the OpenDriver method (see below).
  102.  
  103.     You do not normally need to directly call the Create method; the 
  104.     component is automatically created at run-time.
  105.     
  106.     destructor Destroy; override;
  107.     -----------------------------
  108.     The Destroy method destroys the TVicHW32 component releases the 
  109.     memory allocated to it. If a hardware interrupt was "unmasked" to
  110.     permit direct access, the "mask" is automatically restored, and if 
  111.     the kernel-mode driver was opened, it is automatically closed.
  112.  
  113.     You do not normally need to directly call the Destroy method; the 
  114.     component is automatically destroyed when the application closes.
  115.  
  116.     procedure OpenDriver;
  117.     ---------------------
  118.     Loads the vichwXX.vxd (under Windows 95) or vichwXX.sys (under 
  119.     Windows NT) kernel-mode driver, providing direct access to the 
  120.     hardware. If the kernel-mode driver was successfully opened, the
  121.     boolean ActiveHW property (see below) will be set to True; if the 
  122.     procedure fails, the ActiveHW property will be False.
  123.  
  124.     procedure CloseDriver;
  125.     ----------------------
  126.     Closes the kernel-mode driver and releases memory allocated to it.
  127.     If a hardware interrupt was "unmasked", the "mask" is restored. If the
  128.     driver was successfully closed, the ActiveHW property (see below) will
  129.     be set to False.
  130.  
  131.     property ActiveHW: Boolean; (published, read);
  132.     ----------------------------------------------
  133.     The read-only and run-time ActiveHW property specifies whether the
  134.     kernel-mode driver is open. ActiveHW returns True if the driver is
  135.     open, or False if it is not.
  136.  
  137.  
  138. 5. DIRECT MEMORY ACCESS WITH TVicHW32
  139. =====================================
  140.  
  141. The following function permits direct memory acccess:
  142.  
  143.     function MapPhysToLinear (PhAddr: dWord; Size: dWord): Pointer;
  144.     ---------------------------------------- ----------------------
  145.     Maps a specific physical address to a pointer in linear memory, 
  146.     where PhAddr is the base address and Size is the actual number of
  147.     bytes to which access is required.
  148.  
  149.     Note that a subsequent call to MapPhysToLinear invalidates the 
  150.     previous pointer.
  151.  
  152.     The following example returns a pointer to the system ROM BIOS area:
  153.  
  154.     type 
  155.       TBiosArray = array [0 ..255] of Byte;
  156.       PBiosArray = ^TBiosArray;
  157.  
  158.     var 
  159.       pBIOS: PBiosArray;
  160.  
  161.     begin
  162.       with VicHw32 do
  163.       begin
  164.         OpenDriver;
  165.         if ActiveHW then
  166.         begin
  167.           PBIOS:=MapPhysToLinear ($F8000,256)   // 255 bytes beginning at $F8000
  168.           {...working with pBIOS...}
  169.           CloseDriver;
  170.         end
  171.         else ShowMessage('ERROR: Kernel-mode driver is not open.'); 
  172.       end;
  173.     end;
  174.  
  175. 6. DIRECT PORT I/O WITH TVicHW32
  176. ================================
  177.  
  178. For access to the 80x86 CPU data ports, TVicHW32 provides an implementation of
  179. the traditional Borland Pascal 7 predefined arrays, Port and PortW, and adds PortL 
  180. (which accepts a DWORD) and a "Hard/Soft" boolean switch. 
  181.  
  182. When a value is assigned to an array of type Port, PortW, or PortL, the value is output
  183. to the selected port. When an array of type Port, PortW or PortL is referenced in an 
  184. expression, its value is input from the selected port. Use of the Port, PortW and PortL
  185. arrays are restricted to assignment and reference in expressions only.
  186.  
  187. The following properties permit direct I/O port access:
  188.  
  189.     property Port[Index: Word]: Byte; (public, read, write);
  190.     --------------------------------------------------------
  191.     Value of the Port array is of type Byte.
  192.  
  193.     property PortW [Index: Word]: Word; (public, read, write);
  194.     --------------------------------------- ------------------
  195.     Value of the PortW array is of type Word.
  196.  
  197.     property PortL [Index: Word]: dWord; (public, read, write);
  198.     --------------------------------------- -------------------
  199.     Value of the PortL array is of type DWord.
  200.  
  201.     property HardAccess: Boolean; (published, read, write);     
  202.     --------------------------------------- ---------------
  203.     The HardAccess property determines whether the kernel-mode driver
  204.     should use "hard" or "soft" access to the I/O ports. If set to True
  205.     "hard" access is employed; if set to False "soft" access is employed.
  206.  
  207.     "Soft" access provides higher performance access to ports, but may fail
  208.     if the port(s) addressed are already in use by another kernel-mode 
  209.     driver. While slower, "Hard" access provides more reliable access to
  210.     ports which have already been opened by another kernel-mode driver. 
  211.  
  212.     The following example demonstrates direct port I/O calls, and generally
  213.     complies with traditional Borland Pascal 7 syntax to facilitate porting
  214.     16-bit code to Delphi 2:
  215.  
  216.     with VicHw32 do
  217.     begin
  218.       {...}
  219.       Port[$2F8]:=$34;     // write a byte to port
  220.       {...}
  221.       MyByte:=Port[$2f9];  // read a byte from a port
  222.       {...}
  223.     end;
  224.  
  225.  
  226. 7. HARDWARE INTERRUPT HANDLING WITH TVicHW32
  227. ============================================
  228.  
  229. In a Win32 environment, hardware interrupts are normally hidden or "masked" 
  230. by Windows; the TVicHW32 kernel-mode driver allows you to "unmask" the interrupt 
  231. for direct handling by your application. Note that only one interrupt can be 
  232. handled at a time.
  233.  
  234. The following properties and methods permit access to hardware interrupts.
  235.  
  236.     property OnHwInterrupt: TNotifyEvent; published;
  237.     ------------------------------------------------
  238.     Notification event that a specific hardware interrupt has occurred. 
  239.  
  240.     property IRQNumber: Byte; (published, read, write)
  241.     --------------------------------------------------
  242.     Specifies which hardware interrupt (IRQ1..15) is to be unmasked for 
  243.     processing. Note that IRQ0 (the system timer) is *not* supported.
  244.  
  245.     procedure SetIRQ;
  246.     -----------------
  247.     Assign the interrupt specified by the IRQNumber property to the 
  248.     OnHwInterrrupt event, and sets the IsIRQSet property (see below) to True.
  249.  
  250.     procedure UnmaskInterrupt;
  251.     --------------------------
  252.     Unmasks the hardware interrupt specified by the IRQNumber property, so that
  253.     an OnHWInterrupt event will be generated when a hardware interrupt occurs,
  254.     and sets the Masked property (see below) to False. 
  255.  
  256.     procedure MaskInterrupt;
  257.     ------------------------
  258.     Masks the hardware interrupt specified by the IRQNumber property.
  259.  
  260.     procedure DestroyIRQ;
  261.     ---------------------
  262.     Frees the memory and code previously assigned for unmasking the hardware
  263.     interrupt specified by the IRQNumber property, setting the IsIRQSet property
  264.     to False and the Masked property to True.
  265.  
  266.     property IsIRQSet: Boolean; (read only);
  267.     ----------------------------------------
  268.     Read-only property which specifies whether the hardware interrupt handler has
  269.     been created by the SetIRQ method.
  270.  
  271.     property Masked: Boolean; (read only);
  272.     --------------------------------------
  273.     Read-only property which specifies whether the hardware interrupt handler has
  274.     been removed (True), or is still active (False).
  275.  
  276.     property IRQCounter: dWord; (read only);
  277.     ----------------------------------------
  278.     Read-only property which counts the number of hardware interrupts intercepted
  279.     by the TVicHW32 kernel-mode driver. The IRQCounter property is provided largely
  280.     for debugging purposes, allowing you to compare the actual number of hardware
  281.     interrupts generated with the number processed by your application.
  282.     
  283.     procedure SimulateHwInt;
  284.     ------------------------
  285.     This procedure is provided for purposes of debugging, and allows you to 
  286.     simulate a hardware interrupt. When this procedure is called, the TVicHW32 
  287.     kernel-mode driver will feign a "hardware interrupt", without directly affecting
  288.     the hardware.
  289.  
  290. 8. CONTACT INFORMATION
  291. ======================
  292.  
  293. Comments, questions and suggestions regarding TVicHW32 can be directed by e-mail to
  294. victor@ivi.ugatu.ac.ru or tools@entechtaiwan.com. 
  295.  
  296. With best wishes,
  297.  
  298. Victor Ishikeev
  299. March 1997
  300.